// Physical memory allocator, intended to allocate
// memory for user processes, kernel stacks, page table pages,
// and pipe buffers. Allocates 4096-byte pages.
// 物理内存分配，内存分配给用户空间，内核栈，页表，管道。分配4k页。
#include "types.h"
#include "defs.h"
#include "param.h"
#include "memlayout.h"
#include "mmu.h"
#include "spinlock.h"

void freerange(void *vstart, void *vend);
extern char end[]; // first address after kernel loaded from ELF file
                   // defined by the kernel linker script in kernel.ld

struct run {
  struct run *next;
};

struct {
  struct spinlock lock;
  int use_lock;
  struct run *freelist;
} kmem;

// Initialization happens in two phases.初始化开始在两个周期
// 1. main() calls kinit1() while still using entrypgdir to place just
// the pages mapped by entrypgdir on free list.
// main()函数呼叫kinit1()，仍然使用entrypgdir去分配页通过空闲页
// 2. main() calls kinit2() with the rest of the physical pages
// after installing a full page table that maps them on all cores.
// main调用kinit1(end, P2V(4M))
void
kinit1(void *vstart, void *vend)   
{
  initlock(&kmem.lock, "kmem");
  kmem.use_lock = 0;
  freerange(vstart, vend);
}

void
kinit2(void *vstart, void *vend)
{
  freerange(vstart, vend);
  kmem.use_lock = 1;
}

// 释放开始到结束的内存块
void
freerange(void *vstart, void *vend)
{
  char *p;
  p = (char*)PGROUNDUP((uint)vstart);
  for(; p + PGSIZE <= (char*)vend; p += PGSIZE)
    kfree(p);
}

// Free the page of physical memory pointed at by v,
// which normally should have been returned by a
// call to kalloc().  (The exception is when
// initializing the allocator; see kinit above.)
// 释放v指向的物理内存页，v可以通过kalloc()进行返回
void
kfree(char *v)
{
  struct run *r;

  if((uint)v % PGSIZE || v < end || V2P(v) >= PHYSTOP)
    panic("kfree");
  // Fill with junk to catch dangling refs.
  memset(v, 1, PGSIZE);

  if(kmem.use_lock)
    acquire(&kmem.lock);

  r = (struct run*)v;
  r->next = kmem.freelist;             // 本行将r指向的v的地址给了kmem.freelist
  kmem.freelist = r;                   // 利用头插法建立一个循环链表 

  if(kmem.use_lock)
    release(&kmem.lock);
}

// Allocate one 4096-byte page of physical memory.
// Returns a pointer that the kernel can use.
// Returns 0 if the memory cannot be allocated.
// 分配一个4k物理内存
char*
kalloc(void)
{
  struct run *r;

  if(kmem.use_lock)
    acquire(&kmem.lock);

  // r被复制为freelist的内容，而r就是run1，r的next就是run2
  r = kmem.freelist;
  if(r)
    kmem.freelist = r->next;         //这个函数证明可用物理内存是单项链表，减少行分配
   
  if(kmem.use_lock)
    release(&kmem.lock);
  return (char*)r;           
}
